---
type: integration
title: '@astrojs/react'
description: "Apprenez à utiliser l'intégration de framework @astrojs/react pour étendre la prise en charge des composants dans votre projet Astro."
sidebar:
  label: React
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/react/'
category: renderer
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import Since from '~/components/Since.astro';

Cette **[intégration Astro][astro-integration]** permet le rendu et l'hydratation côté client pour vos composants [React](https://react.dev/).

## Installation

Astro inclut une commande `astro add` pour automatiser l'installation des intégrations officielles. Si vous préférez, vous pouvez [installer les intégrations manuellement](#installation-manuelle) à la place.

Pour installer `@astrojs/react`, exécutez ce qui suit depuis le répertoire de votre projet et suivez les instructions :

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npx astro add react
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm astro add react
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn astro add react
    ```
  </Fragment>
</PackageManagerTabs>

Si vous rencontrez des problèmes, [n'hésitez pas à nous les signaler sur GitHub](https://github.com/withastro/astro/issues) et essayez les étapes d'installation manuelle ci-dessous.

### Installation manuelle

Tout d'abord, installez le paquet `@astrojs/react` :

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npm install @astrojs/react
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm add @astrojs/react
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn add @astrojs/react
    ```
  </Fragment>
</PackageManagerTabs>

La plupart des gestionnaires de paquets installent également les dépendances associées. Si vous voyez un avertissement `Cannot find package 'react'` (ou similaire) lorsque vous démarrez Astro, vous devrez installer `react` et `react-dom` avec ses définitions de type :

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npm install react react-dom @types/react @types/react-dom
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm add react react-dom @types/react @types/react-dom
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn add react react-dom @types/react @types/react-dom
    ```
  </Fragment>
</PackageManagerTabs>

Ensuite, appliquez l'intégration à votre fichier `astro.config.*` en utilisant la propriété `integrations` :

```js ins="react()" ins={2} title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  // ...
  integrations: [react()],
});
```

Et ajoutez le code suivant au fichier `tsconfig.json`.

```json title="tsconfig.json" ins={5-8}
{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "react"
  }
}
```

## Démarrage

Pour utiliser votre premier composant React dans Astro, dirigez-vous vers notre [documentation sur les frameworks UI][astro-ui-frameworks]. Vous y découvrirez :

* 📦 comment les composants de framework sont chargés,
* 💧 les options d'hydratation côté client, et
* 🤝 les possibilités de mélanger et d'imbriquer les frameworks.

## Intégrer des actions avec `useActionState()`

L'intégration `@astrojs/react` fournit deux fonctions à utiliser avec les [actions d'Astro][astro-actions] : `withState()` et `getActionState()`.

Celles-ci sont utilisées avec le [hook useActionState() de React](https://fr.react.dev/reference/react/useActionState) afin de lire et de mettre à jour l'état côté client lorsque des actions sont déclenchées au moment de la soumission du formulaire.

### `withState()`

<p>

**Type :** `(action: FormFn<T>) => (state: T, formData: FormData) => FormFn<T>`<br />
<Since v="4.4.0" pkg="@astrojs/react" />
</p>

Vous pouvez transmettre `withState()` et l'action que vous souhaitez déclencher au hook `useActionState()` de React en tant que fonction d'action du formulaire. L'exemple ci-dessous transmet une action `like` pour augmenter un compteur, avec un état initial de `0` mention « J'aime ».

```jsx title="Like.tsx" ins={2,7} "useActionState"
import { actions } from 'astro:actions';
import { withState } from '@astrojs/react/actions';
import { useActionState } from "react";

export function Like({ postId }: { postId: string }) {
  const [state, action, pending] = useActionState(
    withState(actions.like),
    { data: 0, error: undefined }, // mentions « J'aime » et erreurs initiales
  );

  return (
    <form action={action}>
      <input type="hidden" name="postId" value={postId} />
      <button disabled={pending}>{state.data} ❤️</button>
    </form>
  );
}
```

La fonction `withState()` fera correspondre les types d'actions avec les attentes de React et préservera les métadonnées utilisées pour l'amélioration progressive, lui permettant de fonctionner même lorsque JavaScript est désactivé sur l'appareil de l'utilisateur.

### `getActionState()`

<p>

**Type :** `(context: ActionAPIContext) => Promise<T>`<br />
<Since v="4.4.0" pkg="@astrojs/react" />
</p>

Vous pouvez accéder à l'état enregistré par `useActionState()` sur le serveur dans votre gestionnaire d'actions (`handler`) à l'aide de `getActionState()`. Cette méthode accepte le [contexte de l'API d'Astro](/fr/reference/api-reference/#lobjet-de-contexte), et éventuellement, vous pouvez appliquer un type au résultat.

L'exemple ci-dessous récupère la valeur actuelle des mentions « J'aime » à partir d'un compteur, typée en tant que nombre, afin de créer une action `like` incrémentielle :

```ts title="actions.ts" ins={3,11}
import { defineAction, type SafeResult } from 'astro:actions';
import { z } from 'astro:schema';
import { getActionState } from '@astrojs/react/actions';

export const server = {
  like: defineAction({
    input: z.object({
      postId: z.string(),
    }),
    handler: async ({ postId }, ctx) => {
      const { data: currentLikes = 0, error } = await getActionState<SafeResult<any, number>>(ctx);
      
      // gérer les erreurs
      if (error) throw error;

      // écrire dans la base de données
      return currentLikes + 1;
    },
  })
};
```

## Options

### Combinaison de plusieurs frameworks JSX

Lorsque vous utilisez plusieurs frameworks JSX (React, Preact, Solid) dans le même projet, Astro doit déterminer quelles transformations spécifiques au framework JSX doivent être utilisées pour chacun de vos composants. Si vous n'avez ajouté qu'une seule intégration de framework JSX à votre projet, aucune configuration supplémentaire n'est nécessaire.

Utilisez les options de configuration `include` (obligatoire) et `exclude` (optionnelle) pour spécifier quels fichiers appartiennent à quel framework. Fournissez un tableau de fichiers et/ou de dossiers à `inclure` pour chaque framework que vous utilisez. Des caractères joker peuvent être utilisés pour inclure plusieurs chemins de fichiers.

Nous recommandons de placer les composants communs du framework dans le même dossier (par exemple `/composants/react/` et `/composants/solid/`) pour faciliter la spécification de vos inclusions, mais ce n'est pas obligatoire :

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import preact from '@astrojs/preact';
import react from '@astrojs/react';
import svelte from '@astrojs/svelte';
import vue from '@astrojs/vue';
import solid from '@astrojs/solid-js';

export default defineConfig({
  // Permettre à de nombreux frameworks de prendre en charge tous les différents types de composants.
  // Aucun `include` n'est nécessaire si vous n'utilisez qu'un seul framework JSX !
  integrations: [
    preact({
      include: ['**/preact/*'],
    }),
    react({
      include: ['**/react/*'],
    }),
    solid({
      include: ['**/solid/*'],
    }),
  ],
});
```

### Analyse syntaxique des éléments enfants

Les enfants transmis dans un composant React depuis un composant Astro sont analysés comme des chaînes de caractères simples, et non comme des nœuds React.

Par exemple, le composant `<ReactComponent />` ci-dessous ne recevra qu'un seul élément enfant :

```astro
---
import ReactComponent from './ReactComponent';
---

<ReactComponent>
  <div>un</div>
  <div>deux</div>
</ReactComponent>
```

Si vous utilisez une bibliothèque qui *attend* que plus d'un élément enfant soit passé, par exemple pour qu'elle puisse placer certains éléments à différents endroits, vous pourriez trouver cela bloquant.

Vous pouvez utiliser l'option expérimentale `experimentalReactChildren` pour dire à Astro de toujours passer les enfants à React en tant que nœuds DOM virtuels React. Il y a un coût d'exécution à cela, mais cela peut aider à la compatibilité.

Vous pouvez activer cette option dans la configuration de l'intégration de React :

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  // ...
  integrations: [
    react({
      experimentalReactChildren: true,
    }),
  ],
});
```

### Désactiver le streaming (expérimental)

Astro diffuse par défaut la sortie des composants React. Cependant, vous pouvez désactiver ce comportement en activant l'option `experimentalDisableStreaming`. Cela est particulièrement utile pour prendre en charge les bibliothèques qui ne fonctionnent pas bien avec le streaming, comme certaines solutions CSS-in-JS.

Pour désactiver le streaming pour tous les composants React de votre projet, configurez `@astrojs/react` avec `experimentalDisableStreaming: true` :

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  // ...
  integrations: [
    react({
      experimentalDisableStreaming: true,
    }),
  ],
});
```

[astro-integration]: /fr/guides/integrations-guide/

[astro-ui-frameworks]: /fr/guides/framework-components/#utilisation-des-composants-de-framework
